AddressBook Method (Session Object)
The AddressBook
method displays the MAPI dialog box that allows the user to select entries from
the address book. The selections are returned in a Recipients collection
object.
Syntax
Set objRecipients = objSession.AddressBook( [ recipients, title,
oneAddress, forceResolution, recipLists, toLabel, ccLabel, bccLabel,
parentWindow ] )
Parameters
objRecipients
On successful
return, the Recipients collection object. When the user does not select any
names from the dialog box, AddressBook returns Nothing.
objSession
Required. The
Session object.
recipients
Optional.
Object. A Recipients collection object that provides the initial value for the
recipient list boxes in the address book. (Note: This initial Recipient
collection is ignored in the OLE Messaging Library.)
title
Optional.
String. The title or caption of the address book dialog box. The default value
is an empty string.
oneAddress
Optional.
Boolean. Allows the user to enter or select only one address. The default value
is FALSE.
forceResolution
Optional.
Boolean. If TRUE, attempts to resolve all names before closing the address
book. Prompts the user to resolve any ambiguous names. The default value is
TRUE.
recipLists
Optional.
Long. The number of recipient list boxes to display in the address book dialog
box:
|
recipLists |
Action |
|
0 |
Displays no
list boxes. The user can interact with the address book dialog box but no
recipients are returned by this method. |
|
1 |
Displays
one list box (default) for mapiTo recipients. |
|
2 |
Displays
two list boxes; mapiTo and mapiCc recipients. |
|
3 |
Displays three
list boxes; mapiTo, mapiCc, and mapiBcc recipients. |
toLabel
Optional.
String. The caption for the button associated with the first list box. Ignored
if recipLists is less than 1. If omitted, the default value To: is
displayed.
ccLabel
Optional.
String. The caption for the button associated with the second list box. Ignored
if recipLists is less than 2. If omitted, the default value CC: is
displayed.
bccLabel
Optional.
String. The caption for the button associated with the third list box. Ignored
if recipLists is less than 3. If omitted, the default value BCC: is
displayed.
parentWindow
Optional.
Long. The parent window handle for the address book dialog box. A value of 0
(the default) specifies that any dialog box displayed is application modal.
Remarks
The AddressBook
method returns Nothing if the user cancels the dialog box.
To provide an
access key for the list boxes, include an ampersand (&) character in the
string for the label argument. For example, if toLabel is
&Attendees: , users can press alt+a
to move the focus to the first recipient list box.
When you use
the AddressBook method to let the user select recipients for a new
message, you must use two different Recipients collections. This is required
because the Recipients property of the Message object is read-only. Use
the following procedure:
1. Call Session.AddressBook, which returns
a new Recipients collection.
2. Call Messages.Add to create a new
message.
3. Loop through the Recipients collection
returned by Session.AddressBook, adding each recipient to the message s
Recipients collection by calling the message s Recipients.Add method.
Note that you
must update both the Recipient and the AddressEntry properties of
the destination Recipient object, as demonstrated in the following
example:
Dim objNewRecip(MAX_RECIPS) as Object ' array of new recipients
'...
Set
objNewMessage = objSession.Outbox.Messages.Add
Set
objRecipColl = objSession.AddressBook( _
Title:="Select Recipients", _
recipLists:=3) 'use default labels
' now add
to the new message
Count =
objRecipColl.Count ' error checking
omitted...
With
objNewMessage.Recipients
For i
= 1 To Count Step 1
Set objRecip = objRecipColl.Item(i)
Set objNewRecip(i) = .Add( _
entryID:=objRecip.AddressEntry.ID, _
type:=objRecip.type)
objNewRecip(i).Name = objNewRecip(i).AddressEntry.Name
objNewRecip(i).address = objNewRecip(i).AddressEntry.type _
& ":" & objNewRecip(i).AddressEntry.address
objNewRecip(i).Resolve
Next i
End With
objNewMessage.Update 'save it
The following
methods can also invoke MAPI dialog boxes: Delete and Details
methods (AddressEntry object), Options and Send methods (Message
object), Resolve method (Recipient object and Recipients collection), Logon
method (Session object).
Note The initial
Recipients collection, as specified in the recipients parameter, is not
used in the OLE Messaging Library.
Example
The following
example displays an address book dialog box labeled Select Attendees with
three recipient lists:
If
objSession Is Nothing Then
MsgBox
"must first create MAPI session and logon"
Exit
Function
End If
Set
objRecipColl = objSession.AddressBook( _
Title:="Select Attendees", _
forceResolution:=True, _
recipLists:=3, _
toLabel:="&Very Important People") ' on button
ccLabel:="&Carbon Recipients")
bccLabel:="&Secret Recipients")
' Note:
initial value not used in version 1.0
'
parameter not used in call: Recipients:=objInitRecipColl
MsgBox
"Name of first recipient = " & objRecipColl.Item(1).Name
Exit
Function
See Also
AddressEntry
Object, Recipients Collection1S0GWB8